home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / catD / ioctl.z / ioctl
Encoding:
Text File  |  1998-10-30  |  7.9 KB  |  131 lines
  1.  
  2.  
  3.  
  4. iiiiooooccccttttllll((((DDDD2222))))                                                            iiiiooooccccttttllll((((DDDD2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _iiii_oooo_cccc_tttt_llll - control a character device
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_cccc_rrrr_eeee_dddd_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ffff_iiii_llll_eeee_...._hhhh_>>>>
  15.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_eeee_rrrr_rrrr_nnnn_oooo_...._hhhh_>>>>
  16.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  17.      _iiii_nnnn_tttt _p_r_e_f_i_x_iiii_oooo_cccc_tttt_llll_((((_dddd_eeee_vvvv______tttt _d_e_v_,,,, _iiii_nnnn_tttt _c_m_d_,,,, _vvvv_oooo_iiii_dddd _****_a_r_g_,,,,
  18.             _iiii_nnnn_tttt _m_o_d_e_,,,, _cccc_rrrr_eeee_dddd______tttt _****_c_r_p_,,,, _iiii_nnnn_tttt _****_r_v_a_l_p_))))_;;;;
  19.  
  20.    AAAArrrrgggguuuummmmeeeennnnttttssss
  21.      _d_e_v          Device number.
  22.  
  23.      _c_m_d          Command argument the driver _iiii_oooo_cccc_tttt_llll routine interprets as the
  24.                   operation to be performed.
  25.  
  26.      _a_r_g          Passes parameters between the user and the driver.  The
  27.                   interpretation of the argument is dependent on the command
  28.                   and the driver.  For example, the argument can be an
  29.                   integer, or it can be the address of a user structure
  30.                   containing driver or hardware settings.
  31.  
  32.      _m_o_d_e         Contains the file modes set when the device was opened.  The
  33.                   driver can use this to determine if the device was opened
  34.                   for reading (_FFFF_RRRR_EEEE_AAAA_DDDD), writing (_FFFF_WWWW_RRRR_IIII_TTTT_EEEE), and so on.  See
  35.                   _oooo_pppp_eeee_nnnn(D2) for a description of the values.
  36.  
  37.      _c_r_p          Pointer to the user credential structure.
  38.  
  39.      _r_v_a_l_p        Pointer to the return value for the calling process.  The
  40.                   driver may elect to set the value if the _iiii_oooo_cccc_tttt_llll(D2) succeeds.
  41.  
  42. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  43.      The _iiii_oooo_cccc_tttt_llll(D2) routine provides non-STREAMS character drivers with an
  44.      alternate entry point that can be used for almost any operation other
  45.      than a simple transfer of data.
  46.  
  47.      The _iiii_oooo_cccc_tttt_llll routine is basically a _ssss_wwww_iiii_tttt_cccc_hhhh statement, with each _cccc_aaaa_ssss_eeee
  48.      definition corresponding to a different _iiii_oooo_cccc_tttt_llll command identifying the
  49.      action to be taken.
  50.  
  51.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  52.      The _iiii_oooo_cccc_tttt_llll routine should return 0 on success, or the appropriate error
  53.      number on failure.  The system call will usually return 0 on success or
  54.      -1 on failure.  However, the driver can choose to have the system call
  55.      return a different value on success by passing the value through the
  56.      _r_v_a_l_p pointer.
  57.  
  58.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. iiiiooooccccttttllll((((DDDD2222))))                                                            iiiiooooccccttttllll((((DDDD2222))))
  70.  
  71.  
  72.  
  73. UUUUSSSSAAAAGGGGEEEE
  74.      This entry point is optional, and is valid for character device drivers
  75.      only.
  76.  
  77.      Most often, _iiii_oooo_cccc_tttt_llll is used to control device hardware parameters and
  78.      establish the protocol used by the driver in processing data.  I/O
  79.      control commands are used to implement terminal settings, to format disk
  80.      devices, to implement a trace driver for debugging, and to flush queues.
  81.  
  82.      If the third argument, _a_r_g, is a pointer to user space, the driver can
  83.      use _cccc_oooo_pppp_yyyy_iiii_nnnn(D3) and _cccc_oooo_pppp_yyyy_oooo_uuuu_tttt(D3) to transfer data between kernel and user
  84.      space.
  85.  
  86.      STREAMS drivers do not have _iiii_oooo_cccc_tttt_llll routines.  The stream head converts I/O
  87.      control commands to _MMMM______IIII_OOOO_CCCC_TTTT_LLLL messages, which are handled by the driver's
  88.      _pppp_uuuu_tttt(D2) or _ssss_rrrr_vvvv(D2) routine.
  89.  
  90.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  91.      The _iiii_oooo_cccc_tttt_llll routine has user context and can sleep.
  92.  
  93.    WWWWaaaarrrrnnnniiiinnnnggggssss
  94.      An attempt should be made to keep the values for driver-specific I/O
  95.      control commands distinct from others in the system.  Each driver's I/O
  96.      control commands are unique, but it is possible for user-level code to
  97.      access a driver with an I/O control command that is intended for another
  98.      driver, which can have serious results.
  99.  
  100.      A common method to assign I/O control command values that are less apt to
  101.      be duplicated is to compose the commands from some component unique to
  102.      the driver (such as a module name or ID), and a counter, as in:
  103.      _####_dddd_eeee_ffff_iiii_nnnn_eeee _PPPP_RRRR_EEEE_FFFF_IIII_XXXX           _((((_''''_hhhh_''''_<<<<_<<<<_1111_6666_||||_''''_dddd_''''_<<<<_<<<<_8888_))))
  104.      _####_dddd_eeee_ffff_iiii_nnnn_eeee _CCCC_OOOO_MMMM_MMMM_AAAA_NNNN_DDDD_1111         _((((_PPPP_RRRR_EEEE_FFFF_IIII_XXXX_||||_1111_))))
  105.      _####_dddd_eeee_ffff_iiii_nnnn_eeee _CCCC_OOOO_MMMM_MMMM_AAAA_NNNN_DDDD_2222         _((((_PPPP_RRRR_EEEE_FFFF_IIII_XXXX_||||_2222_))))
  106.      _####_dddd_eeee_ffff_iiii_nnnn_eeee _CCCC_OOOO_MMMM_MMMM_AAAA_NNNN_DDDD_3333         _((((_PPPP_RRRR_EEEE_FFFF_IIII_XXXX_||||_3333_))))
  108. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  109.      _cccc_oooo_pppp_yyyy_iiii_nnnn(D3), _cccc_oooo_pppp_yyyy_oooo_uuuu_tttt(D3), _dddd_rrrr_vvvv______pppp_rrrr_iiii_vvvv(D3), _eeee_rrrr_rrrr_nnnn_oooo_ssss(D5), _oooo_pppp_eeee_nnnn(D2)
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.